home *** CD-ROM | disk | FTP | other *** search
/ C/C++ Users Group Library 1996 July / C-C++ Users Group Library July 1996.iso / vol_400 / 423_01 / accpost / custom.doc < prev    next >
Encoding:
Text File  |  1989-08-31  |  9.9 KB  |  210 lines
  1.              CUSTOM.COM - Customizes Plain Vanilla Progams
  2.                             Not Copyrighted
  3.  
  4. 1. For Users
  5.  
  6. This utility allows you to customize many other Plain Vanilla programs 
  7. if you receive them in a configuration that is not suitable for your 
  8. uses.  You can also use it to customize your own programs if you have 
  9. written them with that in mind.  A program can be customized as many 
  10. times and in as many ways as you wish.  However, if you use several 
  11. different versions of one program, you will have to use the RENAME 
  12. feature of DOS to change their names.
  13.  
  14. To customize a progam, first read the documentation for that program to 
  15. determine whether it can be customized, and whether the features that 
  16. you want to change can be changed in this manner.  This is very 
  17. important, since CUSTOM.COM does not provide any help facilities.
  18.  
  19. Each customizable program contains one or more parameters, such as 
  20. column widths, key codes, or other numbers that describe the required 
  21. characteristics of the program and are used by the program to operate in 
  22. the desired manner.  The CUSTOM.COM utility finds these parameters and 
  23. changes them to the values you specify.
  24.  
  25. Make sure you have at least one other working copy of the program before 
  26. attempting to customize a copy, since an equipment or power failure 
  27. during customization may damage or erase the program.  (Operator error, 
  28. however, usually leads to a nonworking version of the program that can 
  29. be customized again to produce a working version.)  Also, the new 
  30. version will be written right over the old version and will replace it, 
  31. at least in the current directory.
  32.  
  33. Now make sure CUSTOM.COM is in the current directory or is accessible 
  34. through the PATH directive, and that the program to be customized is 
  35. accessible.  Then type
  36.  
  37.           CUSTOM   <file specifications of program>
  38.  
  39. When typing the file specifications of the program, you must include the 
  40. extension (usually .COM), since no default extension will be supplied.  
  41. You may include a drive specification if the program is not on the 
  42. currently logged drive, and you may include a directory path if the 
  43. program is not in the current directory.
  44.  
  45. The CUSTOM.COM utility then displays the name and current value of each 
  46. parameter and prompts you for a new value.  Each parameter is an integer 
  47. in the range from 0 to 65535 (although meaningful values are usually in 
  48. much more restricted ranges).  You will usually have to refer to the 
  49. documentation to determine the desired value of each parameter, because 
  50. the parameter names themselves convey very little information.
  51.  
  52. If the current value of a parameter is not to be changed, just strike 
  53. the "enter" key without entering anything.  Otherwise, enter the 
  54. appropriate integer.  You can use the backspace and other keys to 
  55. correct your mistakes, just as you can when entering a command line for 
  56. DOS.  When you are satisfied with the value you have entered, strike the 
  57. "enter" key.
  58.  
  59. If you strike the "Ctrl-C" key combination at any time before entering 
  60. the last parameter, the customization will be aborted.  The utility will 
  61. usually not be usable, so you should be revert to your backup copy in 
  62. this case.
  63.  
  64. If you should notice an error in the value you entered for a parameter, 
  65. you cannot correct the error once you have struck the "enter" key.  But 
  66. all is not lost.  A program with an incorrect parameter will not work as 
  67. desired, and if the error is serious enough, if may not work at all, but 
  68. it can be customized again.  Just continue with the customization and 
  69. then start over.  Keep pressing the "enter" key until the erroneous 
  70. parameter comes up.  Then enter the correct value, and continue pressing 
  71. the "enter" key until no further parameters come up.
  72.  
  73. If you plan to use the new version of the program along with the old 
  74. version, use the RENAME function of DOS to change the name of the new 
  75. version.  Leave the extension unchanged so the program will load 
  76. properly.
  77.  
  78. 2. For Programmers
  79.  
  80. Writing a customizable program is fairly simple, at least in assembly 
  81. language or C.  Customization parameters must appear in one or more 
  82. customization blocks, consisting of the following bytes:
  83.  
  84.      (1)  The six identification bytes 17H, FDH, 46H, 0FH, 74H and B3H, 
  85.           in precisely that order.  The CUSTOM.COM scans the object code 
  86.           for these six bytes, so the customization block may appear 
  87.           anywhere in the object code.  These six bytes must NOT appear 
  88.           together in this order anywhere in the object code except at 
  89.           the beginning of a customization block.  They were chosen 
  90.           years ago with the help of a random number table, and are 
  91.           extremely unlikely to appear elsewhere by coincidence.
  92.  
  93.      (2)  One or more parameter blocks, consisting of
  94.  
  95.                (a)  The name of the parameter, as it is to be displayed 
  96.                     by the customization program, as a C-style ASCII 
  97.                     string terminated by a zero byte (an ASCII NUL).  Do 
  98.                     not include brackets or a colon.  These will be 
  99.                     supplied by the CUSTOM.COM utility.  The name must 
  100.                     contain at least one character other than the 
  101.                     terminating zero byte.  Most programs will be 
  102.                     slightly more efficient if the name consists of an 
  103.                     even number of ASCII characters (including the 
  104.                     terminating zero byte), since this will put the 
  105.                     parameter value on a word boundary.
  106.  
  107.                (b)  The two-byte parameter value, stored in the usual 
  108.                     manner, with the less significant byte first (at the 
  109.                     lower address).  The value in the source code should 
  110.                     the the default value of the parameter in the 
  111.                     distributed program.  It will be changed as required 
  112.                     by the CUSTOM.COM utility.
  113.  
  114.      (3)  A single zero byte to terminate the customization block.
  115.  
  116. Here is a specimen customization block from a Plain Vanilla utility:
  117.  
  118.      static char id[] = {0x17,0xFD,0x46,0x0F,0x74,0xB3};
  119.      static char par1[] = "Lines on page    ";
  120.      static int lines_on_page = 56;
  121.      static char par2[] = "Line width       ";
  122.      static int line_width = 72;
  123.      static char par3[] = "Top margin       ";
  124.      static int top_margin = 5;
  125.      static char par4[] = "Left margin      ";
  126.      static int left_margin = 5;
  127.      static char par5[] = "LPT (1, 2 or 3)  ";
  128.      static int LPT = 1;
  129.      static char par6[] = "Spacing (1 or 2) ";
  130.      static int spacing = 1;
  131.      static char par7[] = "Pause (1=Y, 0=N) ";
  132.      static int pause_flag = 0;
  133.      static char parx = 0;
  134.  
  135. Here all parameter names have been padded with spaces to the same 
  136. length, which is deliberately made odd so all the parameter values will 
  137. fall on word boundaries.  Every parameter is explicitly initialized, 
  138. even if the default value is 0.  This is required by most C compilers to 
  139. keep the entire block in the same memory segment.  The variable names 
  140. id, par1, par2, ..., par7 and parx are arbitrary.
  141.  
  142. Here is the same customization block in assembly language:
  143.  
  144.                     DB   17H, 0FDH, 46H, 0FH, 74H, 0B3H
  145.                     DB   "Lines on page    ", 0
  146.      LINES_ON_PAGE  DW   56
  147.                     DB   "Line width       ", 0
  148.      LINE_WIDTH     DW   72
  149.                     DB   "Top margin       ", 0
  150.      TOP_MARGIN     DW   5
  151.                     DB   "Left margin      ", 0
  152.      LEFT_MARGIN    DW   5
  153.                     DB   "LPT (1, 2 or 3)  ", 0
  154.      LPT            DW   1
  155.                     DB   "Spacing (1 or 2) ", 0
  156.      SPACING        DW   1
  157.                     DB   "Pause (1=Y, 0=N) ", 0
  158.      PAUSE_FLAG     DW   0
  159.                     DB   0
  160.  
  161. Notice that the terminating zero byte at the end of each parameter name 
  162. is not supplied automatically, as it would be in C.  It must be 
  163. specified explicitly.
  164.  
  165. Writing a customizable program in other languages is a little more 
  166. difficult, but it can usually be done.  You just have to create a 
  167. customization block that will have the required layout in the object 
  168. code with 16-bit parameter values accessible to the rest of the program.  
  169. For example, here is the same customization block in Turbo Pascal 5.0:
  170.  
  171.      id : array[1..6] of byte = ($17,$FD,$46,$0F,$74,$B3);
  172.      par1 : array[1..18] of char = 'Lines on page    '#0;
  173.      lines_on_page : word = 56;
  174.      par2 : array[1..18] of char = 'Line width       '#0;
  175.      line_width : word = 72;
  176.      par3 : array[1..18] of char = 'Top margin       '#0;
  177.      top_margin : word = 5;
  178.      par4 : array[1..18] of char = 'Left margin      '#0;
  179.      left_margin : word = 5;
  180.      par5 : array[1..18] of char = 'LPT (1, 2 or 3)  '#0;
  181.      LPT : word = 1;
  182.      par6 : array[1..18] of char = 'Spacing (1 or 2) '#0;
  183.      spacing : word = 1;
  184.      par7 : array[1..18] of char = 'Pause (1=Y, 0=N) '#0;
  185.      pause_flag : word = 0;
  186.      parx : byte = 0;
  187.  
  188. The block should be put into the constant declaration part of the main 
  189. program.  Notice that in Pascal the terminating zero byte at the end of 
  190. each parameter name is not supplied automatically, as it would be in C.  
  191. It must be specified explicitly.
  192.  
  193. It is permissible to use more than a single customization block in a 
  194. program, provided each one follows this form.  The CUSTOM.COM utility 
  195. should be able to find all of them.
  196.  
  197.  
  198. 3. No Copyright
  199.  
  200. Unlike most other Plain Vanilla software, the CUSTOM.COM utility and 
  201. this documentation file are not copyrighted, at least in their latest 
  202. versions.  You may use them and distribute them with your own programs, 
  203. even if you are selling them.
  204.  
  205. The source code file CUSTOM.ASM, which is also uncopyrighted, is being 
  206. distrubuted along with the object and documentation files.
  207.  
  208. Plain Vanilla Corporation                                 9-1-89
  209. P.O. Box 4493, San Diego CA 92164
  210.